THE UPTIMES PROTOCOL (rev. 5.0) http://uptimes.wonko.com/protocol.php
=====================================================================


What is this document about?
----------------------------
This document will describe the 5th revision of the uptimes protocol,
used to communicate between the uptime client and the server.


Overview
--------
There are two protocols supported by the uptime server. The primary
protocol (which should be used by all clients that aren't behind a
proxy) uses UDP to send client data to the server. The backup protocol
uses HTTP and can be tunneled through an HTTP proxy server. This
document describes the UDP protocol. For information on the HTTP
protocol, look at <http://uptimes.wonko.com/oldprotocol.php>.


Client Requirements
-------------------
In order to meet the specifications of this protocol, a client must:

 * Use UDP to send uptime reports
 * Send the uptime at most once every 30 seconds
 * Send the uptime at least once every 10 minutes
 * Meet the protocol specifications detailed below


Sending the Report
------------------
Uptime reports should be sent via UDP to uptimes.wonko.com on port
49153. The structure of the report is just a simple string, formatted
like this:

    authkey|uptime|load|idle|os|oslevel|cpu|client

So, Wonko's Uptime Client might send the following string:

    51cbb9711de405x06a877z75404be027|415|100.00|0|Windows|2000|i686|WonkoClient/2.1.0

If your client doesn't support CPU load or idle, you could leave those
sections blank, like so:

    51cbb9711de405x06a877z75404be027|415|||Windows|2000|i686|WonkoClient/2.1.0


Now, here's a description of each piece of data:


 * authkey (required)
   This is a 32-character key that is unique for each host. The key
   for each host can be found on the host details page after the host
   is registered.

 * uptime (required)
   Uptime in minutes of the host.

 * load
   A value describing the actual CPU load of the host as a percentage
   from 0 to 100, in the form '100.00'.

 * idle
   This describes the percentage of the total uptime that the host was
   completely idle. The value can vary from '0' to '100'.  It should
   be noted that this is an all-inclusive calculation, and it should
   represent the total cumulative percentage of time that the host has
   been idle, not just the percentage of idle CPU time as the current
   moment.

 * os (required)
   Operating system or platform of the host. This should be a string
   no longer than 32 characters. It should be one of the values below.

   - AIX
   - BeOS
   - BSDi
   - Darwin
   - Embedded
   - FreeBSD
   - HPLaser
   - HPUX
   - IRIX
   - IRIX64
   - Linux
   - MacOS
   - NetBSD
   - Netware
   - OpenBSD
   - OpenVMS
   - QNX
   - RiscRouter
   - SunOS
   - TINI OS
   - Ultrix
   - Unixware
   - VAX
   - Windows

(For additions, email <ryan@wonko.com>)

 * oslevel (required)
   Version of the host's operating system. Examples are "2.0.37",
   "XP", "4.11".

 * cpu
   This key describes the CPU of the machine. You are advised, but not
   restricted, to use one of the following strings:

   - alpha
   - DS80C390
   - i386
   - i486
   - i586
   - i686
   - MIPS
   - pa-risc
   - ppc
   - sparc
   - sun4m
   - sun4c
   - sun4u
   - VAX

(For additions, email <ryan@wonko.com>)

 * client
   This is an optional string, no longer than 32 characters, the
   describes the client. Usually it should be the client's name and
   version number, and optionally the version number of the protocol
   the client supports. Wonko's Uptime Client sends the string
   WonkoClient/2.1.0.

Return Values
-------------
Since UDP is a sessionless protocol, the server will not send a
message back when you send a report. You'll just have to hope you got
the data formatted right. In order to be at least a little helpful,
I've added a field called "UDP Status" to the host details page of
hosts that you own. Assuming you at least send the correct authkey,
this field will be updated to contain the latest status or error
message from the server.

Faking
------
Now that you know the protocol, it's easy to write a client that fakes
its uptime. Personally, I think hosts running FreeBSD 4.6.2 with
uptimes over 3 years are pretty stupid. Maybe you think
differently. In any case, hosts with fake uptimes will be marked bogus
and ignored in the statistics, so there's really no point in wasting
your time.


Uptimes Protocol (rev. 5.0) - 09/09/2002, <ryan@wonko.com>

Copyright  2003 Ryan Grove. All rights reserved.
